<html><head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"><title>Project 2 - Wiretap</title>
<link href="prj2_files/style.css" rel="stylesheet" type="text/css"></head><body>

<h2><center>Project 2: Wiretap</center></h2>
<h2><center> Assigned: 10/06/08, Due: <strong> 10/20/08 </strong>
</center> </h2><br>

<h2> Project Goal </h2> 

Programs such as <strong>tcpdump</strong> (<a href="http://www.tcpdump.org/">http://www.tcpdump.org/</a>) and
<strong>Wireshark</strong>
(<a href="http://www.wireshark.org/">http://www.wireshark.org/</a>)
allow the interception and analysis of packets being transmitted or
received over a LAN.  One prominent use of this information is in
troubleshooting network configuration and reachability.  In this
project, we will provide you with data captured using these tools.
Your task is to write the analysis routines similar to those provided
by <strong>tcpdump</strong> and <strong>Wireshark</strong>.  Your
program must be written in C/C++ and should work on the Burrow or
Sharkestra Linux machines.

<h2> Project Specification </h2>

<p> Your program, <em>wiretap</em>, should take a file containing
<strong>tcpdump</strong> data as its input and output the statistics detailed
later in this document.  Since this data is not in human-readable format, you
will have to use the <em>Packet Capture Library</em>, <em>libpcap.a</em>, and
the functions in its header file, <em>pcap.h</em> (found in /usr/include on the
CS Linux machines) to read the data.  When compiling your program, include the
<em>pcap</em> library by using <em>-lpcap</em> as the first argument to your
GNU compiler. For example, <em>gcc -lpcap -o wiretap wiretap.c</em> will
compile a C program with the <em>pcap</em> library support. For C++, simply
change the compiler from <em>gcc</em> to <em>g++</em>. The other steps you
should follow are:</p>

<ul>

<li> Open an input file using function <em>pcap_open_offline()</em>.</li>

<li> Check that the data you are provided has been captured from Ethernet using
function <em>pcap_datalink()</em>.</li>

<li> Read packets from the file using function <em>pcap_loop()</em>.  Note
that this function needs to be called only once.  It takes 4 arguments.  Of
these, the second and the third arguments are of most interest to you.  The
second argument lets you specify how many packets to read from the file.  The
third argument, <em>pcap_handler callback</em>, is where most of the action
happens.  Here, <em>callback</em> is the function you write to process data
from each packet.<br><br>

You can pass the callback function to the <em>pcap_loop()</em>
function simply by giving its name as the appropriate argument to
<em>pcap_loop()</em>. The callback function must be a void function
that takes three arguments, of the types <em>u_char *, const struct
pcap_pkthdr *, const u_char *</em>. The callback is called by
<em>pcap_loop()</em> once for each packet. The second argument
to the callback is the special libpcap header, which can be used to
extract the entire packet length and the packet arrival time (see the
<em>pcap_pkthdr</em> structure in <em>/usr/include/pcap.h</em>). The
third argument contains the contents of a single packet (from the
Ethernet packet header onward).</li>

<li> Close the file using function <em>pcap_close()</em>.</li>

</ul>

<h3> Packet format</h3>

<p> Each packet in the file(s) provided to you is in
<strong>tcpdump</strong> format.  It contains a tcpdump-specific
header, an Ethernet header, followed by network layer headers and
their payloads. These packet captures will contain IP and ARP headers
at the network layer, UDP at the transport layer, and DHCP at the
application layer. You will need to understand each of the header
formats to accomplish this task. You are encouraged to reuse the
structures from the relevant Ethernet, IP, and UDP header files in the
<em>/usr/include/net</em> and <em>/usr/include/netinet</em>
directories on the CS Linux machines. These files contain structures
used by the Linux operating system for actual packets. They can be
used to greatly simplify the process of parsing the packets. However,
you are still free to implement the structures on your own, if you
wish. </p>

<h3> Program output</h3>

<p> The <em>callback</em> function should gather statistics from each packet to
enable your program to print the following on standard out:</p>

<ul>

<li> Start date and time of the packet capture</li>

<li> Duration of packet capture</li>

<li> Total packets</li>

<li> Unique Ethernet addresses, along with the total number of packets
containing each address. Represent Ethernet addresses in
<em>hex-colon</em> format.</li>

<li> Unique IP addresses, along with the total number of packets containing 
each address. Represent the IP addresses in the standard a.b.c.d notation.</li>

<li> Unique ARP participants, their associated MAC addresses, and IP
addresses.</li>

<li> For UDP, list the unique ports seen, either as source or as destination.</li>

<li> For UDP, determine the number of packets with a correct checksum,
  an incorrect checksum, and those that omit checksum calculations.</li>

<li> Unique DHCP clients and servers, listed separately. Indicate the
  number of packets transmitted by each client or server.</li>

<li> Report the number of DHCP packets that are DHCPDISCOVER,
  DHCPOFFER, DHCPREQUEST, and DHCPACK.</li>

<li>Average, minimum, and maximum packet sizes.  Here, packet refers to
everything beyond the <strong>tcpdump</strong> header.</li>

<!--<li>Average, minimum, and maximum <em>overhead</em>.  Here, overhead
refers to the Ethernet and network layer header sizes with respect to
the entire packet for non-UDP traffic.  For UDP traffic, overhead also
includes the UDP header. Here, packet refers to everything beyond
the <strong>tcpdump</strong> header.</li> -->

</ul>

<h3> Test files</h3>

<p>The following are two packet captures you should use for testing purposes.</p>

<ul>
<li><a href="http://www.cs.indiana.edu/classes/p538/projects/dhcp.pcap">Packet Capture 1</a>: A simple DHCP example</li>
<li><a href="http://www.cs.indiana.edu/classes/p538/projects/http.pcap">Packet Capture 2</a>: HTTP traffic</li>
</ul>

<p>Your program should work on packet captures that have additional
  protocols your program does not understand. Additional test files
  may be used during the demo.</p>



<h2> Miscellaneous</h2>

<ul>

<li> If you have root access on any machine, install
<strong>Wireshark</strong> and experiment with it.</li>

<li> Resource: <a href="http://www.tcpdump.org/pcap.htm">http://www.tcpdump.org/pcap.htm</a></li>

<li> Use the <em>ntohs</em> and <em>ntohl</em> functions as appropriate to
read values that span multiple bytes.  This ensures that the bytes are in
proper byte order (Endianness) for use at this host. </li>

</ul>

<h2> Extra Credit</h2>

<p> For 5% extra credit, process TCP headers and report unique ports seen in TCP traffic. Also, indicate the number of
  packets with the SYN flag set, the number with the ACK flag set, and the number with the FIN flag.</p>

<h2> Deliverables and Grading</h2>

<p> The grading will be based on the following three deliverables, all of which
are due by 11.59pm on the due date: </p>

<ul> 

  <li> <b> Project report:</b> Prepare a report (up to 2 pages)
detailing your implementation.  For each major component of the
project, the report should provide any algorithms and assumptions you
made in your program.  Also, list any known limitations of your
program, including portions that are not implemented or do not work
correctly.  The report should use a 10-point font, with one inch
margins.  Submit the report in <em>pdf</em> format with your code
(more details below).  No other format, e.g. <em>doc</em>
or <em>docx</em>, will be accepted.  Print your project report
double-sided and bring the hard copy to the demo.</li>

<li> <b> Code submission and demo: </b> Submit your code, and project
report files as a single archive file (.tar or .tar.gz file formats
only) via <a href="http://oncourse.iu.edu/">OnCourse</a>. Shortly
after the submission deadline, demo slots will be posted on
the <a href="https://www.cs.indiana.edu/cgi-pub/p538/demos/">Demonstration
Scheduling System</a> (a reminder will be posted on
the <a href="https://www.cs.indiana.edu/cgi-pub/p538/fall2008/wwwboard/">Web
Board</a> by <b>Craig Shue</b>). You must schedule an appointment to
demonstrate your project; groups that fail to demonstrate their
project will not receive credit for the project. If a group member
fails to attend his or her scheduled demonstration time slot, it will
result in a 10 point reduction in his or her grade.</li>

<li> <b> Partner evaluation: </b> You must evaluate your project
  partner. You must submit the evaluation using the <a href="https://www.cs.indiana.edu/cgi-pub/p538/demos/evals.php">Partner
  Evaluations</a> page. You will receive a copy of the evaluation by
  email as confirmation. Failure to submit this evaluation by the
  project submission deadline will result in a 10 point reduction in
  your grade.</li>

</ul>

</body></html>